Fox's Git Mirrors - /page/blob.mu

Node / rns-mirrors / Reticulum-Go.git / files / docs / en / utilities.md

Displaying Rendered • View raw • Download

Go-native tools that speak the same shared-instance msgpack RPC and identity file formats as Python rnstatus, rnid, rnprobe, rnpath, rncp, and rnx. They are not Python clones.

They ship as subcommands of the single T383838reticulum-go binary:

T282828

make build

./bin/reticulum-go status

./bin/reticulum-go id -h

./bin/reticulum-go probe ...

./bin/reticulum-go path -t

./bin/reticulum-go cp -l

./bin/reticulum-go x -l

./bin/reticulum-go sh -l

./bin/reticulum-go pageserver

T383838make install also creates legacy symlinks (rgostatus, rgoid, rgoprobe, rgopath, rgocp, rgox, rnx, rgosh, rgopageserver, rgoslow, rgospeed, rgodump, rgosnap, rgoselfcheck) that invoke the same binary. Man pages: man reticulum-go, man reticulum-go-status, man reticulum-go-speedtest, man reticulum-go-self-check, and so on.

┌────────────────────────────────────────┬──────────────────────────┬──────────────────────────────┐

│ Tool / subcommand │ Python counterpart │ Role │

├────────────────────────────────────────┼──────────────────────────┼──────────────────────────────┤

│ T383838reticulum-go status (rgostatus) │ rnstatus │ Interface and transport sta… │

│ T383838reticulum-go slow (rgoslow) │ (Go-only) │ Bottleneck and local health… │

│ T383838reticulum-go id (rgoid) │ rnid │ Identity generate, hash, T383838.r… │

│ T383838reticulum-go probe (rgoprobe) │ rnprobe │ Path wait, encrypted probe,… │

│ T383838reticulum-go path (rgopath) │ rnpath │ Path table, drop, blackhole… │

│ T383838reticulum-go cp (rgocp) │ rncp │ File send / listen / fetch … │

│ T383838reticulum-go x (rgox, rnx) │ rnx │ Remote command execution ov… │

│ T383838reticulum-go sh (rgosh) │ rnsh (native + T383838--compat) │ Interactive remote shell ov… │

│ T383838reticulum-go pageserver │ (example app) │ NomadNet-style page and fil… │

│ T383838reticulum-go self-check (rgoselfcheck) │ (Go-only) │ Host OS preflight for sandb… │

│ T383838reticulum-go speedtest (rgospeed) │ T383838Examples/Speedtest.py │ Loopback smoke plus cross-h… │

│ T383838reticulum-go dump (rgodump) │ (Go-only) │ Decode RNS packets from hex… │

│ T383838reticulum-go snapshot (rgosnap) │ (Go-only) │ Path table, links, and heal… │

└────────────────────────────────────────┴──────────────────────────┴──────────────────────────────┘

Library code lives in T383838pkg/rnsutil and T383838pkg/cli. Pageserver logic lives in T383838pkg/pageserver.

Packet capture and Wireshark docs live in packet-debug.md. The cross-stack T383838INTEROP_EVENT timeline is in interop-timeline.md.

rgostatus and T383838rgopath -t / drop / blackhole modes dial a running shared instance (Python rnsd or T383838reticulum-go) over the same multiprocessing.connection + msgpack protocol Python uses.

RPC is fully supported on both transports:

┌────────────────────┬─────────────────────────────────────────────────────────────────────┐

│ shared`*instance`*type │ Listen / dial address │

├────────────────────┼─────────────────────────────────────────────────────────────────────┤

│ tcp │ T383838127.0.0.1:<instance_control_port> (default 37429) │

│ unix │ Abstract socket T383838@rns/<instance_name>/rpc (Linux) │

│ unset │ Platform default: unix on Linux, tcp elsewhere (matches Python RNS) │

└────────────────────┴─────────────────────────────────────────────────────────────────────┘

Go implements both server and client for TCP and Unix. When the type is unset, utilities try the platform default first, then the other transport, so stock Linux Python rnsd works without forcing TCP.

Issues that usually stack:

1. Wrong config directory. Python uses T383838~/.reticulum. Go defaults to T383838~/.reticulum-go. Point T383838-config at the directory of the daemon you are querying.

2. Explicit transport mismatch. If one side sets T383838shared_instance_type = tcp and the other unix, dials miss. Leave the key unset on Linux, or set the same value on both.

3. Daemon not sharing. The process that owns interfaces must have T383838share_instance = yes and be running.

4. Auth key mismatch. Align rpckey, or share the same derived transportidentity.

Stock Linux Python already uses abstract Unix sockets. Point Go tools at that config directory:

T282828

./bin/reticulum-go status -config ~/.reticulum

./bin/reticulum-go status -config ~/.reticulum -json

./bin/reticulum-go path -config ~/.reticulum -t -json

Optional shared auth key in both configs (recommended when mixing stacks):

T282828

[reticulum]

share_instance = yes

instance_name = default

shared_instance_type = unix

rpc_key = <64 hex characters>

Generate a key once:

T282828

python3 -c 'import secrets; print(secrets.token_hex(32))'

Restart rnsd after editing rpc_key. Go tools with unset or unix type dial T383838@rns/default/rpc.

Use TCP when you want the same recipe on every OS, or when mixing with an older Go daemon that bound TCP:

T282828

[reticulum]

share_instance = yes

instance_name = default

shared_instance_type = tcp

shared_instance_port = 37428

instance_control_port = 37429

rpc_key = <64 hex characters>

Restart the daemon after editing so it binds TCP T383838127.0.0.1:37429.

┌────────────────────────────┬──────────────────────────────────────────────────────────────┐

│ Config │ Authkey used │

├────────────────────────────┼──────────────────────────────────────────────────────────────┤

│ rpc_key set (64 hex chars) │ That exact 32-byte key │

│ rpc_key empty │ SHA-256 of the daemon T383838storage/transport_identity private key │

└────────────────────────────┴──────────────────────────────────────────────────────────────┘

Go and Python must agree. Prefer an explicit shared rpc_key when mixing stacks so you do not depend on identical transport identity files.

Run T383838reticulum-go with T383838share_instance = yes under T383838~/.reticulum-go. Unset type follows the platform default (Unix on Linux):

T282828

./bin/reticulum-go status -config ~/.reticulum-go -json

./bin/reticulum-go path -config ~/.reticulum-go -t

Only one process should own the shared instance ports (or Unix RPC name) at a time.

T282828

rgostatus [flags]

┌──────────────┬─────────────────────────────────────────────────────────────────────────────┐

│ Flag │ Meaning │

├──────────────┼─────────────────────────────────────────────────────────────────────────────┤

│ T383838-config dir │ Config directory (default: T383838~/.reticulum-go) │

│ T383838-json │ Emit JSON (bytes as hex, same field names as Python where populated) │

│ T383838-a │ Include all interfaces (less filtering of local/client peers) │

│ T383838-n substr │ Filter interface names │

│ T383838-l │ Include link count │

│ T383838-s key │ Sort by rate, rx, tx, rxs, txs, traffic, announce, arx, atx, prx, ptx, held │

│ T383838-r │ Sort ascending (default descending) │

│ T383838-timeout dur │ RPC timeout (default 10s) │

└──────────────┴─────────────────────────────────────────────────────────────────────────────┘

JSON includes per-interface announce and path-request frequencies, held announces, burst flags, and traffic counters when the daemon provides them.

Against a Go daemon, human and JSON output also include local mesh health fields when counters are non-zero: ifacfail, hmacfail, announcesigfail, unpackfail, integrityfailrate, stalecloses, keepalive_timeout, and related totals. Python rnsd does not populate these keys. Missing fields mean zero or unknown, not a protocol error.

T282828

reticulum-go slow [flags]

# legacy: rgoslow

Ranks congestion and local health signals that commonly explain stalled transfers or noisy interfaces. Uses the same shared-instance RPC as status (interface_stats plus path table).

┌──────────────┬─────────────────────────────────────────────┐

│ Flag │ Meaning │

├──────────────┼─────────────────────────────────────────────┤

│ T383838-config dir │ Config directory (default: T383838~/.reticulum-go) │

│ T383838-json │ Emit full JSON report │

│ T383838-a │ Include all interfaces │

│ T383838-n substr │ Filter interface names │

│ T383838-l │ Include link count │

│ T383838-dest hash │ Focus analysis on a destination (32 hex) │

│ T383838-top n │ Max interfaces to rank (default 12) │

│ T383838-high-hop n │ Hop count treated as high (default 6) │

│ T383838-m │ Continuously refresh │

│ T383838-I dur │ Monitor interval (default 2s) │

│ T383838-timeout dur │ RPC timeout (default 10s) │

└──────────────┴─────────────────────────────────────────────┘

Bottleneck findings cover bitrate utilization, announce/PR bursts, held announces, bandwidth gates, socket RTT, and high-hop paths.

When talking to a Go daemon, health findings can also appear:

┌──────────────────┬────────────────────────────────────────────────────────────────┐

│ Kind │ Meaning │

├──────────────────┼────────────────────────────────────────────────────────────────┤

│ integrity_burst │ Elevated IFAC/HMAC/unpack fail rate vs accepted frames │

│ auth_pressure │ Announce signature or link proof rejects clustered on an iface │

│ link_degraded │ Rising stale closes or keepalive timeouts │

│ ingress_pressure │ Held announces or burst limiters active │

└──────────────────┴────────────────────────────────────────────────────────────────┘

Counters stay local to the node. slow only observes and scores. It does not change ingress policy or blackhole tables.

T282828

reticulum-go speedtest [flags]

# legacy: rgospeed

Link throughput test modeled on Python T383838Examples/Speedtest.py.

┌───────────────────────────────┬───────────────────────────────────────────┐

│ Mode │ Command │

├───────────────────────────────┼───────────────────────────────────────────┤

│ Loopback smoke (default / CI) │ T383838reticulum-go speedtest or T383838-loopback │

│ Server (oneshot) │ T383838reticulum-go speedtest -l │

│ Daemon (VPS / docker) │ T383838reticulum-go speedtest -daemon │

│ Client (cross-host) │ T383838reticulum-go speedtest <server_dest_hash> │

└───────────────────────────────┴───────────────────────────────────────────┘

Destination is T383838speedtest.server. Server and client must use the same T383838-bytes size. After the transfer the server sends a T383838SPEEDOK ack with the confirmed RX count. Networked clients pace sends (100 µs per packet by default) so UDP sockets are not overrun; loopback does not pace.

Every run prints a grep-friendly T383838speedtest_result ... line on stdout (visible in T383838docker logs). With T383838-json, a JSON object follows on stdout as well.

Use a real config with UDP/TCP (or a shared path). shareinstance is forced off so the tool owns its interfaces. Python-style forwardip / forwardport are accepted as aliases for targethost / target_port.

┌────────────────┬─────────────────────────────────────────────────────────────┐

│ Flag │ Meaning │

├────────────────┼─────────────────────────────────────────────────────────────┤

│ T383838-loopback │ In-process pipe (CI liveness, default when no args) │

│ T383838-l │ Listen as server (one client then exit) │

│ T383838-daemon │ Listen forever (implies T383838-l -m, default announce every 120s) │

│ T383838-m │ Listen: serve multiple clients │

│ T383838-iface │ all (default) or comma-separated config section names │

│ T383838-p │ Print identity / destination hash and exit │

│ T383838-config dir │ Config directory (default T383838~/.reticulum-go) │

│ T383838-identity path │ Persistent identity for listen mode │

│ T383838-bytes n │ Plaintext bytes to transfer (default 2 MiB) │

│ T383838-min-bps n │ Fail below this rate (T3838380 disables; loopback defaults to 1e6) │

│ T383838-timeout sec │ Overall timeout (default 60) │

│ T383838-announce sec │ Listen announce interval (T3838380 once, T383838<0 never) │

│ T383838-json │ Emit JSON after each speedtest_result line │

│ T383838-q │ Quieter debug │

└────────────────┴─────────────────────────────────────────────────────────────┘

Cross-host example (two machines / configs with a shared path):

T282828

# server

reticulum-go speedtest -daemon -iface tcp -bytes 4194304

# client (paste the 32-hex hash printed by the server)

reticulum-go speedtest -iface tcp -bytes 4194304 <hash_from_server>

Build and run a persistent public TCP listener:

T282828

task docker:build:speedtest

docker run -d --name rgo-speedtest -p 4242:4242 \\

-e SPEEDTEST_IFACE=tcp \\

-v reticulum-go-speedtest:/data \\

reticulum-go-speedtest:latest

docker logs -f rgo-speedtest

Env knobs: T383838SPEEDTEST_IFACE (all or names), T383838SPEEDTEST_BYTES, T383838SPEEDTEST_ANNOUNCE, T383838SPEEDTEST_PORT, T383838SPEEDTEST_JSON, T383838RNS_CONFIG. Persist T383838/data so the identity (and thus dest hash) stays stable for CI secrets.

CI client config needs a TCPClientInterface to the VPS host:port and the printed dest hash. Treat measured rates as a path floor (runner to VPS), not a lab loopback number.

Nightly CI runs T383838task test-link-speed (TestLinkSpeedSmoke) with a 512 KiB loopback cap and a 1 MB/s floor.

Identity and signing tool. Files are wire-compatible with Python:

┌───────────┬─────────────────────────────────────────────────────────────────────┐

│ Extension │ Format │

├───────────┼─────────────────────────────────────────────────────────────────────┤

│ T383838.rid │ 64 raw bytes (X25519 private + Ed25519 seed) │

│ T383838.rsg │ 64-byte Ed25519 signature + msgpack envelope (hashtype, hash, meta) │

│ T383838.rsm │ Same as T383838.rsg with embedded message │

│ T383838.rfe │ Chunked identity encrypt (same token layout as Python) │

└───────────┴─────────────────────────────────────────────────────────────────────┘

Examples:

T282828

./bin/reticulum-go id -g ~/.reticulum-go/id.rid -p

./bin/reticulum-go id -i ~/.reticulum-go/id.rid -H rns.id

./bin/reticulum-go id -i id.rid -s file.bin -f

./bin/reticulum-go id -i id.rid -V file.bin

./bin/reticulum-go id -i id.rid -S "hello" -w note -f

./bin/reticulum-go id -i id.rid -S @inventory.txt -w reticulum-go.rsm -f

./bin/reticulum-go id -V note.rsm

./bin/reticulum-go id -i e46112d44649266d71fe2193e00a4710 -V reticulum-go.rsm -extract

./bin/reticulum-go id -i id.rid -e secret.txt -f

./bin/reticulum-go id -i id.rid -d secret.txt.rfe -f

T383838-S @path reads the message body from a file (needed for large tree inventories). T383838-extract prints only the embedded RSM message after a successful verify. T383838-i may be a 32-character identity hash when verifying (no private key required).

Go-signed T383838.rsg / T383838.rsm / T383838.rfe validate with Python rnid, and the reverse also works.

T282828

rgoprobe [flags] <full_name> <destination_hash_hex>

Attaches as a shared-instance client (or starts local transport), waits for a path, sends encrypted probes, and prints RTT. Example:

T282828

./bin/reticulum-go probe -config ~/.reticulum -n 3 -v app.aspect aabbccddeeff00112233445566778899

Path table and blackhole management over shared-instance RPC, plus a default path-request mode that attaches like rgoprobe.

T282828

rgopath [flags] [destination_hash]

┌────────────────┬────────────────────────────────────────┐

│ Flag │ Meaning │

├────────────────┼────────────────────────────────────────┤

│ T383838-config dir │ Config directory │

│ T383838-t │ Show path table (optional hash filter) │

│ T383838-json │ JSON for T383838-t / T383838-blackholed │

│ T383838-m N │ Max hops filter for path table │

│ T383838-d │ Drop path to hash │

│ T383838-D │ Drop all paths via transport hash │

│ T383838-q │ Drop announce queues │

│ T383838-w sec │ Path request timeout (default 15) │

│ T383838-blackholed │ List blackholed identities │

│ T383838-blackhole │ Blackhole identity hash │

│ T383838-unblackhole │ Lift blackhole │

│ T383838-for hours │ Blackhole duration (0 = indefinite) │

│ T383838-reason str │ Blackhole reason │

│ T383838-filter substr │ Filter blackhole list lines │

└────────────────┴────────────────────────────────────────┘

Go extras (compat preserved): T383838-json on path and blackhole lists, drop-via count in the success line, clearer path-found summary after a successful request.

Remote rnstransport management modes from Python rnpath are not ported yet.

File transfer over links. Destination name is T383838rncp.receive so Go and Python peers interoperate.

T282828

rgocp [flags] <file> <destination_hash> # send

rgocp -l [flags] # listen

rgocp -f -F <remote_path> [flags] <hash> # fetch

┌────────────────┬─────────────────────────────────────────────────┐

│ Flag │ Meaning │

├────────────────┼─────────────────────────────────────────────────┤

│ T383838-config dir │ Config directory │

│ T383838-identity path │ Identity file (default T383838storage/identities/rncp) │

│ T383838-l │ Listen for pushes │

│ T383838-f / T383838-F path │ Fetch remote file │

│ T383838-a │ Allow unauthenticated senders (listen) │

│ T383838-allowed hash │ Allowed identity (repeatable) │

│ T383838-allow-fetch │ Enable fetch_file requests │

│ T383838-jail dir │ Restrict fetch paths │

│ T383838-save dir │ Save directory for received files │

│ T383838-overwrite │ Overwrite on receive │

│ T383838-no-compress │ Disable auto compression │

│ T383838-announce sec │ Announce interval (T3838380 once, T383838<0 never) │

│ T383838-w sec │ Path/link timeout │

│ T383838-s │ Silent progress │

│ T383838-p │ Print identity and destination hash │

└────────────────┴─────────────────────────────────────────────────┘

Allow lists are loaded from T383838/etc/rncp/allowed_identities, T383838~/.config/rncp/, T383838~/.rncp/, plus Go-specific T383838~/.config/rgocp/ and T383838~/.rgocp/.

Go extras: cleaner progress lines on stderr, T383838-json is not used (transfer is binary), unique T383838.N rename when not overwriting.

Remote command execution over links. Destination name is T383838rnx.execute, request path command (wire-compatible with Python rnx).

T282828

reticulum-go x -l [flags] # listen

reticulum-go x [flags] <destination_hash> <cmd> # execute

reticulum-go x -x [flags] <destination_hash> # interactive

┌─────────────────────────┬────────────────────────────────────────────────┐

│ Flag │ Meaning │

├─────────────────────────┼────────────────────────────────────────────────┤

│ T383838-config dir │ Config directory │

│ T383838-i path │ Identity file (default T383838storage/identities/rnx) │

│ T383838-l │ Listen for commands │

│ T383838-x │ Interactive REPL │

│ T383838-a hash │ Allowed identity (repeatable, listen) │

│ T383838-n │ Accept from anyone (listen) │

│ T383838-N │ Do not identify to listener │

│ T383838-b │ Skip announce on listen start │

│ T383838-m │ Mirror remote exit code │

│ T383838-d │ Detailed timing/size summary │

│ T383838-w sec │ Path/link/command timeout │

│ T383838-W sec │ Max result download time │

│ T383838--stdin str │ Remote stdin │

│ T383838--stdout N / T383838--stderr N │ Max returned bytes │

│ T383838-json │ Structured JSON result (Go) │

│ T383838-p │ Print identity and destination hash │

└─────────────────────────┴────────────────────────────────────────────────┘

Allow lists: T383838/etc/rnx/, T383838~/.config/rnx/, T383838~/.rnx/, plus T383838~/.config/rgox/ and T383838~/.rgox/.

Exit codes match Python rnx (241-249 for client failures, T383838-m mirrors remote).

Interactive remote shell over Link + Channel. Native protocol uses destination app T383838rgosh. T383838--compat speaks Python T383838rnsh (app T383838rnsh, umsgpack message bodies).

T282828

reticulum-go sh -l [flags] [command...] # listen

reticulum-go sh [flags] <destination_hash> [command...] # connect

reticulum-go sh --compat -l # Python rnsh wire protocol

┌────────────────┬────────────────────────────────────────────────┐

│ Flag │ Meaning │

├────────────────┼────────────────────────────────────────────────┤

│ T383838-config dir │ Config directory │

│ T383838-i path │ Identity file │

│ T383838-s name │ Service name (identity file suffix) │

│ T383838-l │ Listen for sessions │

│ T383838-a hash │ Allowed identity (repeatable, listen) │

│ T383838-n │ Accept from anyone (listen) │

│ T383838-N │ Do not identify to listener │

│ T383838-b │ Skip announce on listen start │

│ T383838-C │ Forbid remote cmdline (forced default command) │

│ T383838--compat │ Python rnsh wire protocol │

│ T383838--line / T383838--raw │ Force line-buffered or raw stdin │

│ T383838-m │ Mirror remote exit code │

│ T383838-w sec │ Path/link timeout │

│ T383838-p │ Print identity and destination hash │

└────────────────┴────────────────────────────────────────────────┘

Allow lists: T383838/etc/rgosh/, T383838~/.config/rgosh/, T383838~/.rgosh/, plus Python rnsh paths. Auto line mode engages when link RTT is high unless T383838--raw.

Live interop:

T282828

RUN_LIVE_INTEROP=1 PYTHON_INTEROP=python3 RETICULUM_PATH=/path/to/reticulum \\

go test -v ./tests/interop/ -run 'Rgosh|Rnsh'

┌───────────────────────────────────────────────────────┬──────────────────────────────────────────┐

│ Symptom │ Fix │

├───────────────────────────────────────────────────────┼──────────────────────────────────────────┤

│ T383838dial tcp 127.0.0.1:37429: connection refused │ Start the daemon. If type is explicit t… │

│ T383838dial unix @rns/...: connection refused │ Daemon is on TCP only, or instancename … │

│ T383838rpc auth failure │ Align rpc_key, or use the same T383838storage/… │

│ Empty or missing announce rates from Python │ Field is present but may be T3838380 until tra… │

│ Top-level rxb/txb are T3838380 while interfaces show traffic │ Python aggregate totals often omit some… │

│ Identity load log lines on stderr │ Harmless debug from loading transportid… │

│ rgocp transfer ignored │ Listener needs T383838-a or an allow-list entr… │

└───────────────────────────────────────────────────────┴──────────────────────────────────────────┘

┌─────────────────────────┬────────────────────────────────────────────────────────────────────────┐

│ Tool │ Role │

├─────────────────────────┼────────────────────────────────────────────────────────────────────────┤

│ T383838reticulum-go status │ Interface stats over shared-instance RPC (T383838-json, T383838-q), including Go in… │

│ T383838reticulum-go slow │ Bottleneck and local health findings (integrityburst, authpressure, l… │

│ T383838reticulum-go path -t │ Path table dump │

│ T383838reticulum-go debug │ Effective config path, log level, platform, RPC reachability (T383838-rates,… │

│ T383838reticulum-go self-check │ Host OS preflight checklist (T383838--json, T383838--quick, T383838--full, T383838--strict) │

│ T383838reticulum-go probe │ Connectivity / RTT (T383838-json) │

│ Control API │ HTTP T383838/v1/health (liveness), T383838/v1/status (iface stats plus integrity fi… │

│ Daemon T383838-debug N │ Override config loglevel for one run │

└─────────────────────────┴────────────────────────────────────────────────────────────────────────┘

TTY colors (status Up/Down, probe/path/cp/id outcomes, pageserver banner, daemon text log levels) honor T383838NO_COLOR (off) and T383838FORCE_COLOR / T383838CLICOLOR_FORCE (on). JSON output and file logs stay plain.

• Configuration for shareinstance, ports, and rpckey

• Compatibility for Python utility parity

• Getting started for first daemon run

• Package map for T383838pkg/rnsutil

• Links, channels, and resources for resource wire details